home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Magazine / Online / tcpdl / tcpdl.doc < prev    next >
Text File  |  1998-11-08  |  34KB  |  977 lines
  1. tcpdl V2.5 distribution                                October 1998
  2.  
  3.  
  4. CONTENTS
  5. ========
  6.  
  7. This archive consists of the following files:
  8.  
  9.   tcpdl 2.5a      the tcpdl http download program
  10.  
  11.   tcpdlpp 1.5     the post processor for downloaded pages
  12.  
  13.   tcpdl.doc       this document
  14.  
  15.   tcpdl_html      a subdirectory containing a version of this document
  16.                   in html.
  17.  
  18.   urllist         example urllist file
  19.  
  20.   tcpdl.config    example tcpdl.config file
  21.  
  22.   tcpdlpp.config  example tcpdlpp.config file
  23.  
  24.  
  25. INTRODUCTION
  26. ============
  27.  
  28. tcpdl is a program to download files from http hosts. It can follow
  29. links and can therefore be used to download whole web sites.
  30.  
  31. tcpdlpp is a program to post process files that have been downloaded
  32. by tcpdl. This amends the URLs within each html file so that the 
  33. downloaded pages may be used locally, while any URLs that have not
  34. been downloaded refer to their full URL.
  35.  
  36.  
  37. COPYRIGHT
  38. =========
  39.  
  40. tcpdl is Copyright © 1996 Patrik Nilsson
  41.          Copyright © 1997, 1998 Ramjam Consultants Ltd
  42.  
  43. tcpdlpp is Copyright © 1997, 1998 Ramjam Consultants Ltd
  44.  
  45. This archive is freely distributable, but may not be included in any 
  46. commercial software collection other than Aminet without prior permission.
  47.  
  48.  
  49. REQUIREMENTS
  50. ============
  51.  
  52. To use tcpdl you need a TCP/IP stack and a connection to a http host.
  53.  
  54. Both tcpdl and tcpdlpp should work on any Amiga system which supports
  55. a TCP stack.
  56.  
  57. In use tcpdl typically requires approx 1Mb of RAM plus 500 bytes for
  58. each file to be downloaded, and tcpdlpp requires about 100K plus
  59. 100 bytes per file to be processed.
  60.  
  61. Disk space equivalent to about twice the size of the files to be 
  62. downloaded is also required (in worst case situations).
  63.  
  64.  
  65. SUPPORT
  66. =======
  67.  
  68. Please report any problems, and send any suggestions or comments to:
  69.  
  70.   support@ramjam.u-net.com
  71.  
  72. The most recent version will always be available from 
  73.  
  74.   http://www.ramjam.u-net.com/
  75.  
  76. Major versions may also be available from Aminet.
  77.  
  78. There is no requirement to register use of this program, but anyone
  79. doing so will be kept informed of updates.
  80.  
  81. Both programs have been optimised for the 68000 processor in order to 
  82. be as generic as possible.
  83.  
  84.  
  85. KNOWN PROBLEMS
  86. ==============
  87.  
  88. tcpdl:
  89.  
  90. - doesn't resolve links from HTML with a <BASE> specification correctly
  91.   (a fix is planned for a future version)
  92.  
  93. - doesn't allow access to sites which require a userid/password.
  94.   (enhancement planned for a future version)
  95.  
  96. - doesn't support the automatic download of URLs referenced by the
  97.   name attribute of the object tag. This is because the name attribute
  98.   does not always apply to a URL. Since the object tag is only supported
  99.   by IE3, and the name attribute refers to a URL that is likely to be
  100.   applicable only to IE3, this is not seen as a significant restriction.
  101.   (no fix planned)
  102.  
  103. tcpdlpp:
  104.  
  105. - doesn't handle links from HTML with a BASE specification correctly
  106.   (a fix is planned for version 1.6)
  107.  
  108.  
  109. DISCLAIMER
  110. ==========
  111.  
  112. A great deal of effort has gone into making these programs as reliable
  113. as possible. However, there is no guarantee that they will perform as
  114. described in all cases. 
  115.  
  116. These programs are used entirely at the user's own risk. No liability
  117. can be accepted for loss of data resulting from the use of these 
  118. programs.
  119.  
  120.  
  121. AKNOWLEDGEMENTS
  122. ===============
  123.  
  124. Thanks to Patrik Nilsson for the original version of tcpdl.
  125.  
  126. Thanks to David Stroud for producing an html version of this document.
  127.  
  128. Thanks also to all the users of tcpdl for their comments and suggestions.
  129.  
  130.  
  131. CHANGES FROM PREVIOUS RELEASE
  132. =============================
  133.  
  134. tcpdl
  135. -----
  136.  
  137. V2.5 -> V2.5a:
  138.  
  139. - Fixed a problem where the leading enclosing quotes around URLs
  140.   in downloaded HTML files were omitted.
  141.  
  142. V2.4a -> V2.5:
  143.  
  144. - Added a NOWAIT option to allow tcpdl to exit without waiting for 
  145.   return to be pressed. This option can be used from the command
  146.   line, or can be specified in the config file.
  147.  
  148. - Added a size gadget to the status window which allows the width
  149.   of the window to be adjusted (the height is fixed by the number
  150.   of tasks specified).
  151.  
  152. - Added a PUBSCREEN option to allow tcpdl to open its status window
  153.   on a specified public screen. If no public screen is specified, 
  154.   then the Workbench screen will be used by default as in previous
  155.   versions. This option can be used from the command line, or can
  156.   be specified in the config file.
  157.  
  158. - Added a FONT option to allow the font to be used by the tcpdl status
  159.   window to be specified. By default the Xen font will be used,
  160.   or the default font if Xen is not found. This option can be used
  161.   from the command line, or can be specified in the config file.
  162.  
  163. - Added a FONTSIZE option to allow the size of the font to be used
  164.   by the tcpdl status window to be specified. By default a size of
  165.   9 is used.  This option can be used from the command line, or can
  166.   be specified in the config file.
  167.  
  168. - Added a PRIORITY option to allow the maximum priority of the 
  169.   tcpdl tasks to be specified. By default a priority of 2 is used.
  170.   This option can be used from the command line, or can be specified
  171.   in the config file.
  172.  
  173. V2.4 -> V2.4a:
  174.  
  175. - fixed a bug that caused non-text files to be downloaded even
  176.   when the previously downloaded version was still current.
  177.   This wasted bandwidth unnecessarily. Thanks to Jon Wareham
  178.   for reporting this problem.
  179.  
  180. V2.3c -> V2.4:
  181.  
  182. - reworked the code that deals with the http transfer. This should
  183.   make the code more tolerant of strange replies from the server,
  184.   and has paved the way for further improvements in the future.
  185.  
  186. - changed behaviour when URLs containing characters that are invalid
  187.   in AmigaDOS file names are encountered. Any invalid characters are
  188.   now encoded as %xx where xx is the hex value of that character.
  189.   This is transparent to web browsers and servers, as this form of
  190.   encoding is standard. The encoded filename will be used in HTML
  191.   references, as well as in the file name itself.
  192.   Previously, a CRC encoding was added to the file name, making it
  193.   hard to determine what the original file name was. This ensured it 
  194.   was unique, but introduced its own problems.
  195.  
  196. - changed behaviour when filenames are longer than allowed by the
  197.   filesystem being used. Filenames are now simply truncated at 
  198.   the maximum supported length (30 characters for FFS). The full
  199.   URL without truncation will appear in HTML references.
  200.   Previously, the filename was truncated and a CRC encoding was
  201.   added. The new approach could lead to filename clashes (where
  202.   more than one file in a directory has the same name) but this
  203.   is expected to cause fewer problems than the CRC encoding.
  204.   Note that the encoding of characters (described above) that are
  205.   invalid in filenames may cause filenames to exceed the length
  206.   limit and be truncated.
  207.  
  208. - added the NOSAVE command line option. When specified this 
  209.   prevents any downloaded files from being saved.
  210.   This feature has been requested by users that use tcpdl to
  211.   prime local proxy servers (e.g. httpproxy) with files. If
  212.   tcpdl also saved the files, there would be 2 copies stored 
  213.   locally.
  214.  
  215. - added the DEBUG command line option. When specified this 
  216.   stores a copy of the HTTP request in each DATA file, and
  217.   leaves data files from failed transfers in the TEMP directory.
  218.   This is intended for use in investigating problems only,
  219.   and isn't intended ffor general use.
  220.  
  221. - added new status messages
  222.   "*BREAK*" indicates that the task has noticed the ctrl-C
  223.   "Not Found" indicates that the URL was not found on the server
  224.   "SRVR ERROR" indicates that the server reported an error
  225.  
  226. - previously, some temporary file were written to t:, which could 
  227.   cause problems in low memory situations. All files are now 
  228.   written to tcpdldir: so the user has control of the location
  229.   of all files generated (even temporarily) by tcpdl.
  230.  
  231. - corrected display of current and total file sizes. Previously
  232.   these were displayed only intermittently.
  233.  
  234. - corrected minor bug in the status display which caused columns
  235.   not to be correctly aligned
  236.  
  237. - reduced memory usage slightly
  238.  
  239. - corrected a bug that could leave some files locked if an error
  240.   occured during a download
  241.  
  242.  
  243. V2.3b -> V2.3c:
  244.  
  245. - added URL command line option. This allows a URL to be downloaded to
  246.   be specified on the command line rather than in the urllist file.
  247.   See the Command Line Options section below for details.
  248.  
  249. - added CONFIG command line option. This can be used to specify the
  250.   configuration file to be used. If it is not specified, the default
  251.   tcpdldir:tcpdl.config is used as previously.
  252.  
  253. - added TASKS command line option to allow the number of tasks to be 
  254.   used in downloading URLs to be specified. Valid range is 1 to 15.
  255.  
  256. - added TASKS config option. If present, this value acts as the default
  257.   number of tasks to be used in downloading URLs. Valid range is 1 to 15.
  258.   This value can be overridden by use of the command line TASKS option.
  259.  
  260. - added USERAGENT config option. If present, this specifies the user
  261.   agent name to be sent to the HTTP server. By default the user agent
  262.   name used will be of the form "tcpdl/<version>", where <version>
  263.   is the current version number. This can be used to spoof as some
  264.   other HTTP client, for (broken) sites which only accept requests from 
  265.   certain browsers.
  266.  
  267. - reduced the default number of processes to 12, as 15 was too much
  268.   for many machines.
  269.  
  270. - changed command line option handling to use AmigaDOS templates.
  271.  
  272. V2.3a -> V2.3b:
  273.  
  274. - tcpdl sent http commands that some hosts didn't like - it should now
  275.   manage to talk to hosts using any version of HTTP.
  276.  
  277. - The UPDATE flag wasn't correctly propogated to all the URLs referenced
  278.   by the files marked with UPDATE in the urllist.
  279.   This was a fundamental design flaw, and so the UPDATE flag has been
  280.   removed and replaced by an UPDATE command line option which applies
  281.   to all URLs in urllist.
  282.  
  283. - The IMG flag didn't quite do what was advertised, so it has been 
  284.   amended slightly:
  285.   TEXT means all URLs that are referenced by a "href" attribute
  286.   IMG  means all URLs that are referenced by an attribute other than "href"
  287.   ALL  means all URLs that are referenced
  288.   
  289. - added a configuration option USER, which allows the mail address to be
  290.   used in the HTTP commands to be specified. By default tcpdl uses the
  291.   username and host name used by the tcp/ip stack. If the USER option
  292.   is specified with no mail address, then no From: header will be 
  293.   sent in HTTP commands.
  294.  
  295. - tcpdl used to send the user's realname to the http host - there is no
  296.   need to do this, so now it doesn't.
  297.  
  298. - fixed the DISK-ERR message, which looked untidy.
  299.  
  300. V2.3 -> V2.3a:
  301.  
  302. - made it possible to exit tcpdl when run from Workbench
  303.  
  304. - fixed enforcer hits when urllist contains a blank line
  305.  
  306. V2.2 -> V2.3:
  307.  
  308. - added support for proxy servers
  309.  
  310. - added configuration options for connection, and htpp transfer timeouts
  311.  
  312. - added configuration option for the number of retries for failed
  313.   transfers
  314.  
  315. - tcpdl now uses memory pools for its memory allocation. This improves
  316.   the allocation times slightly, but has a dramatic effect on the 
  317.   deallocation time. It also reduces the risk of memory "leakage" when
  318.   tcpdl is interrupted.
  319.  
  320. - the User Agent name has been changed to conform to RFC2068
  321.  
  322. - the tcpdl.config file is now closed as soon as it has been read
  323.  
  324. - the environment variable USERNAME is now used if USER is not set
  325.  
  326. - changed the ERROR status indicator to be more specific about the
  327.   cause of the error
  328.  
  329. V2.1 -> V2.2:
  330.  
  331. - added tcpdl.config to allow the specification of file types that are
  332.   not to be downloaded.
  333.  
  334. V2.0 -> V2.1:
  335.  
  336. - fixed problem where URLs in the urllist file which were not followed
  337.   by at least one space or tab character were ignored.
  338.  
  339.  
  340. tcpdlpp
  341. -------
  342.  
  343. V1.3 -> V1.4:
  344.  
  345. - changed the handling of URLs with a leading '/'. All URLs are now
  346.   converted to relative form, so all local links should work when
  347.   browsing off-line.
  348.  
  349. V1.2 -> V1.3:
  350.  
  351. - minor optimizations
  352.  
  353. V1.1 -> V1.2:
  354.  
  355. - improved the handling of ".." in URLs
  356.  
  357. - added optional translation of characters in URLs, by means of a new
  358.   configuration file "tcpdldir:tcpdlpp.config" 
  359.  
  360.  
  361. USING TCPDL AND TCPDLPP
  362. ======================
  363.  
  364. OVERVIEW:
  365. ---------
  366.  
  367. Both tcpdl and tcpdlpp expect the assign tcpdldir: to refer to a directory.
  368. This directory is the work area for both programs.
  369.  
  370. By default, the urllist file, containing the list of URLs to be downloaded
  371. is expected to be in this directory. The optional configuration files,
  372. tcpdl.config and tcpdlpp.config are also expected to be in this directory.
  373.  
  374. When tcpdl downloads URLs it will create three directories below tcpdldir:,
  375. TEMP, DATA and HTTP. TEMP is as its name suggests used only for temporary
  376. work files. Beneath DATA and HTTP one directory will be created for each
  377. host, and beneath each of these will be the directories and files which are
  378. downloaded.
  379.  
  380. The HTTP directory contains the actual files that are downloaded, while the
  381. DATA directory contains files holding information about each file downloaded.
  382.  
  383. Example:
  384.  
  385. the following directory tree shows the structure that might result from use
  386. of the example URLs given in the "THE TCPDLDIR:URLLIST FILE" section below.
  387.  
  388.  
  389.          tcpdldir:
  390.             |
  391.             |
  392.             +------- urllist
  393.             |
  394.             |
  395.             +------- TEMP 
  396.             |         |
  397.             |         |
  398.             |        ...
  399.             |
  400.             |
  401.             +------- HTTP 
  402.             |         |
  403.             |         |
  404.             |         +------- www.ramjam.u-net.com
  405.             |         |                  |
  406.             |         |                  |
  407.             |         |                  +------- index.html
  408.             |         |                  |
  409.             |         |                  |
  410.             |         |                  +------- amiga
  411.             |         |                  |          |
  412.             |         |                  |          |
  413.             |         |                 ...        ...
  414.             |         |
  415.             |         |
  416.             |         +------- www.amiga.com
  417.             |         |                  |
  418.             |         |                  |
  419.             |         |                  +------- index.html
  420.             |         |                  |
  421.             |         |                  |
  422.             |        ...                ... 
  423.             |
  424.             |
  425.             +------- DATA 
  426.                       |
  427.                       |
  428.                       +------- www.ramjam.u-net.com
  429.                       |                  |
  430.                      ...                ...
  431.  
  432.  
  433. Thus, once a file has been downloaded, it appears within a directory that
  434. identifies the host from which it came.
  435.  
  436. The DATA directory is used by tcpdl during the download and update process.
  437. The final files appear in the HTTP directory. The DATA/HTTP directory
  438. tree will mirror the actual HTTP directory tree, but the files contain
  439. the HTTP response from the server which includes information that
  440. tcpdl uses. This information includes the date and time of download 
  441. (used when performing an UPDATE), and for html files, a list of all 
  442. the URLs that are referenced.
  443.  
  444. The TEMP directory holds temporary files during processing by tcpdl.
  445. Unless the DEBUG option is specified, all temporary files should be
  446. deleted by tcpdl upon exit. Any files that are left behind in this
  447. directory may be safely deleted.
  448.  
  449. The HTML files downloaded by tcpdl will have references to URLs replaced by
  450. a reference to a local file, e.g.
  451.  
  452.   http://www.ramjam.u-net.com/home.html
  453.  
  454. will become
  455.  
  456.   file://localhost/tcpdldir:http/www.ramjam.u-net.com/home.html
  457.  
  458. The post processor, tcpdlpp, processes all files within the tcpdldir:http
  459. directory and converts references to other files that are present in this
  460. file hierarchy to relative URLs, and converts all other references back to
  461. absolute URLs.
  462.  
  463. This allows the files within the tcpdldir:http directory to be browsed 
  464. offline, while allowing links to other URLs to be followed if the user 
  465. happens to be online. By downloading your favourite pages, you can browse 
  466. the web much faster, while still being able to follow links to other sites.
  467.  
  468. The downloaded pages may be updated periodically using tcpdl with the
  469. UPDATE option, and then running tcpdlpp again to adjust any amended
  470. references.
  471.  
  472.  
  473. TO START:
  474. ---------
  475. 1. assign "tcpdldir:" to the directory which is to contain the 
  476.    downloaded files (this directory should exist).
  477.    (e.g. "assign tcpdldir: work:tcpdldir")
  478. 2. Edit the file tcpdldir:urllist such that it contains the files
  479.    to be downloaded.
  480. 3. edit tcpdldir:tcpdl.config as required
  481. 4. edit tcpdldir:tcpdlpp.config as required
  482. 5. check that there is enough disk space for the pages you intend 
  483.    to download
  484. 6. connect to the Internet
  485. 7. run "tcpdl" from a shell
  486. 8. if required, run "tcpdlpp" from a shell (this can be done offline).
  487.  
  488. If on checking the output of tcpdlpp there are a lot of references
  489. to a non-local URL you may want to use tcpdl to download that URL.
  490. After downloading it, re-run tcpdlpp to change all links to that
  491. URL to refer to the local file.
  492.  
  493.  
  494. COMMAND LINE OPTIONS:
  495. ---------------------
  496.  
  497. tcpdl accepts a number of command line options.
  498.  
  499. URL=<URL specification>
  500.  
  501.   The URL specification can either be just a URL, or a URL with download
  502.   options as in the urllist file. If options are specified, then the
  503.   URL and options must all be enclosed within quotes.
  504.  
  505.   e.g.
  506.  
  507.   tcpdl url=http://www.ramjam.u-net.com/
  508.  
  509.   tcpdl url="http//www.ramjam.u-net.com/ TEXT"
  510.  
  511. URLLIST=<file>
  512.  
  513.   The URLLIST option specifies a file containing a list of URLs to be 
  514.   downloaded.  If this option is not specified then "tcpdldir:urllist"
  515.   is used by default. See the section "THE TCPDLDIR:URLLIST FILE" for
  516.   details of the format of this file.
  517.  
  518. CONFIG=<file>
  519.  
  520.   The CONFIG specifies a file containing configuration options. If this
  521.   option is not specified then "tcpdldir:tcpdl.config" is used by 
  522.   default. See the section "THE TCPDLDIR:tcpdl.config FILE" for details
  523.   of the format of this file.
  524.  
  525. TASKS=<number>
  526.  
  527.   The TASKS option specifies how many URLs will be downloaded at once.
  528.   This overrides any TASKS value specified in tcpdl.config. The valid
  529.   range of values is 1 to 15. 
  530.   
  531. UPDATE
  532.  
  533.   The UPDATE option specifies that any file that has been downloaded
  534.   will be checked to see whether it has been updated since then. If
  535.   it has it will be downloaded again.
  536.  
  537. NOSAVE
  538.  
  539.   The NOSAVE option specifies that the downloaded files should not be
  540.   saved. This may be useful if tcpdl is used to prime a local proxy
  541.   server, or in testing http servers.
  542.  
  543. NOWAIT
  544.  
  545.   The NOWAIT option specifies that tcpdl won't wait for return to be
  546.   pressed before exiting. This makes it easier to use tcpdl from
  547.   within scripts.
  548.  
  549. DEBUG
  550.  
  551.   The DEBUG option specifies that the files within the DATA hierarchy
  552.   should contain a copy of the HTTP request that was sent to the
  553.   server, as well as the response and other usual information. It
  554.   also disables the deletion of temporary files from the TEMP directory
  555.   for transfers that failed. This can be useful when investigating the 
  556.   reason for failed transfers.
  557.  
  558. PUBSCREEN=<name>
  559.  
  560.   The PUBSCREEN option specifies the name of the public screen that
  561.   the tcpdl window will be opened on. By default the Workbench screen
  562.   will be used.
  563.  
  564. FONT=<name>
  565.  
  566.   The FONT option specifies the name of the font that the tcpdl window
  567.   should use. Note that the .font suffix should not be specified.
  568.   Note also that a monospaced font should be used (a proportional
  569.   font will cause the columns not to align correctly).
  570.  
  571. FONTSIZE=<number>
  572.  
  573.   The FONTSIZE option specifies the size of the font the tcpdl window
  574.   should use. The size of the tcpdl status window will be adjusted 
  575.   accordingly. By default a size of 9 is used - if you have a very
  576.   high screen resolution you may wish to increase the font size.
  577.  
  578. PRIORITY=<number>
  579.  
  580.   The PRIORITY option specifies the maximum priority to be used by the
  581.   tcpdl tasks. Priorities must be in the range 0 to 5 inclusive. By 
  582.   default a priority of 2 will be used. Using a value of 0 may be 
  583.   useful if you want tcpdl to operate in the background while you
  584.   are using a browser or IRC client.
  585.  
  586.  
  587.  
  588. TCPDL TASK STATUS WINDOW:
  589. -------------------------
  590.  
  591. The tcpdl status window is updated approx. once per second (Note that 
  592. not every change in status will have a chance to appear in the window).
  593.  
  594. tcpdl can download a number of files at once. There is one line in the
  595. status window for each of these tasks. The fields on each line are
  596. described below:
  597.  
  598. Status:         one of the following values:
  599.                 "Connecting"    Trying to connect a host.
  600.                 "Sending"       Sending request.
  601.                 "Header"        Receiving header.
  602.                 "Updating"      Requesting using "If-Modified-Since" from 
  603.                                 a host or loading data from tcpdldir:data/
  604.                 "OK"            File downloaded successfully
  605.                 "Receiving"     Receiving data.
  606.                 "Wait. html"    A limit of 512k html-data to process.
  607.                                 Processing will continue when the amount 
  608.                                 outstanding falls below the limit.
  609.                 "Proc. html"    Processing html.
  610.                 "Copying"       Copying html-file to tcpdldir:http/
  611.                 "Not Found"     The server reported the URL not found 
  612.                 "LIB ERR"       Unable to open bsdsocket.library
  613.                 "HOST ERR"      Unknown  or unreachable host
  614.                 "SOCK ERR"      Unable to open socket
  615.                 "CON ERR"       Unable to connect to host
  616.                 "HDR ERR"       Failed to download header
  617.                 "RECV ERR"      Failed while receiving data
  618.                 "FILE ERR"      Failed to open output file
  619.                 "SRVR ERR"      Server reported an error
  620.                 "DISK ERR"      Failed while writing to output file
  621.                                 (most likely the disk is full)
  622.                 "ERROR"         Some other error occurred
  623.                 "*BREAK*"       The task has recognised a user break
  624.                                 or an error is causing an abort (e.g.
  625.                                 the disk is full)
  626.  
  627. Time:           elapsed time since trying to connect
  628.  
  629. CPS:            the current download rate achieved for this file 
  630.  
  631. CSize:          the current size of the data received
  632.  
  633. FSize:          the final size of the data, if given by the server
  634.  
  635. Request:        the URL requested
  636.  
  637.  
  638. The top line of the status window also contains an overall progress indicator
  639.  
  640. (DONE:<n> TOTAL:<m>):      <n> the number of files downloaded so far
  641.                            <m> the number of files listed in memory 
  642.  
  643.  
  644. The bottom line of the status window gives some overall performance figures:
  645.  
  646. Total time:     the elapsed time since tcpdl started execution
  647.  
  648. Total bytes:    the total number of bytes downloaded so far
  649.  
  650. Average cps:    the average number of characters per second downloaded 
  651.  
  652.  
  653. OTHER NOTES:
  654. ------------
  655.  
  656. Execution may be terminated using CTRL+C. The program exits as fast as
  657. is possible safely. It can take a little while if it is processing large 
  658. htmlfiles at the time. As each task notices the CTRL-C, the status will
  659. change to "*BREAK*".
  660.  
  661. If a particular host times out on more than 5 occasions, no further attempts
  662. are made to download any files from that host. This avoids wasting time
  663. attempting to connect to a host that is down.
  664.  
  665.  
  666. THE FILE "TCPDLDIR:urllist":
  667. ----------------------------
  668.  
  669. The urllist file should contain one or more URLs which are to be downloaded.
  670.  
  671. Each URL should start on a new line, and be followed by the appropriate
  672. flags, separated by spaces.
  673.   
  674. The supported flags are:
  675.  
  676. D1, D2, ...,  D19          downloading n levels of text/html
  677.                            DEFAULT 255 (!)
  678.  
  679. H0, H1, ...,  H5           If another host is referenced by a HREF
  680.                            max number of levels is set to n.
  681.                            DEFAULT H0, current host only.
  682.  
  683. P0, P1, ...,  P5           If path is other than given in your urllist
  684.                            max number of levels is set to n. 
  685.                            DEFAULT Pn, where n is the same as for Dn
  686.  
  687. TEXT                       download files referenced by a "href"
  688.                            attribute. These will commonly, but not
  689.                            exclusively, be HTML files.
  690.  
  691. IMG                        download files referenced an attribute
  692.                            other than "href". These are commonly,
  693.                            but not exclusively, images.
  694.  
  695. ALL                        download all types of files. This is the
  696.                            default if none of IMG, TEXT, ALL are specified.
  697.                            (Note that this will not download files with
  698.                            types that appear in IGNORE lines within
  699.                            tcpdl.config)
  700.  
  701.  
  702. e.g.
  703.  
  704. http://www.amiga.com/index.html      D2 H3 TEXT
  705.  
  706.      will download 2 levels of html files referenced by the specified file
  707.      from www.amig.com, and 3 levels of links to any other host.
  708.  
  709. http://www.ramjam.u-net.com/home.html  D5 H0 ALL 
  710.  
  711.      will download 5 levels of files referenced by the specified file
  712.      from www.ramjam.u-net.com, but will not download any files that
  713.      are referenced on any other host.
  714.  
  715. http://www.ramjam.u-net.com/ TEXT
  716.  
  717.      will download all text files referenced by the default home page
  718.      from the host www.ramjam.u-net.com.
  719.  
  720.  
  721. THE FILE "TCPDLDIR:tcpdl.config":
  722. ---------------------------------
  723.  
  724. The tcpdl.config file is optional. If present, it will be read in and
  725. the contents will be used in determining what file types will be 
  726. downloaded.
  727.  
  728. Any line with a hash ('#') in column 1 will be ignored as a comment.
  729.  
  730. White space is ignored, and the commands are not case-sensitive.
  731.  
  732. Currently the following configuration commands are suported: 
  733.  
  734. IGNORE <suffix>
  735.  
  736.   where <suffix> is a file suffix which should not be downloaded. Note
  737.   that such files mentioned explicitly in urllist will be downloaded,
  738.   but any such files referenced within html will not.
  739.  
  740.   Note that <suffix> may contain any characters except white space,
  741.   but will only be matched against the end of a file name.
  742.  
  743. PROXY <proxyserver:port>
  744.  
  745.   this specifies that all http requests shpould be sent via the 
  746.   specified server. If the port number is omitted, then a default 
  747.   of 8080 is used.
  748.  
  749.   By specifying your ISP's proxy server you can improve download
  750.   speeds significantly - especially for busy sites.
  751.  
  752.   A proxy will also be required for connections via a firewall.
  753.  
  754. CONTIMEOUT <seconds>
  755.  
  756.   this specifies the initial timeout for each connection in seconds. 
  757.   The default is 20. The timeout must be within the range 10 to 600.
  758.   
  759. HTTPTIMEOUT <seconds>
  760.  
  761.   this specifies the timeout for each http request in seconds. 
  762.   The default is 60. The timeout must be within the range 10 to 600.
  763.   
  764. RETRIES <number>
  765.  
  766.   this specifies the number of attempts that will be made to download
  767.   each file. The default is 5. The value must be within the range 
  768.   1 to 100.
  769.   
  770. USER <mail address>
  771.  
  772.   the mail address is sent to the HTTP server as the address that 
  773.   mail can be sent to if there are problems caused by tcpdl's requests.
  774.   If the USER option is specified without a mail address, then 
  775.   HTTP requests will not include any mail address (this can help
  776.   maintain your anonymity). If the USER option is not present in 
  777.   the config file, then your current user id and host name are
  778.   used.
  779.  
  780. TASKS <number>
  781.  
  782.   the number of URLs that will be downloaded concurrently. If this 
  783.   option is not specified then the default of 12 will be used.
  784.   The valid values are 1 to 15. This value may be overridden by
  785.   the TASKS command line option.
  786.  
  787. USERAGENT  <string>
  788.  
  789.   the string specifies the user agent name that will be sent to the
  790.   HTTP server. The string is assumed to start at the first non-blank
  791.   character after the USERAGENT keyowrd, and to run until the end
  792.   of the line - so it may contain spaces. This option allows tcpdl
  793.   to appear as if it is some other http client, which is necessary
  794.   to access some (broken)  sites which only accept requests from 
  795.   certain browsers.
  796.  
  797. NOWAIT
  798.  
  799.   this specifies that tcpdl will not wait for return to be pressed
  800.   before it exits. This option is useful if tcpdl is run from within
  801.   a script.
  802.  
  803. PUBSCREEN <name>
  804.  
  805.   this specifies the name of the public screen that the tcpdl status
  806.   window should use. This can be overridden by the PUBSCREEN command
  807.   line option.
  808.  
  809. FONT <name>
  810.  
  811.   this specifies the name of the font that the tcpdl status window
  812.   should use. Note that the .font suffix should not be given, and 
  813.   for best results only monospaced fonts should be used. This option
  814.   can be overridden by the FONT command line option.
  815.  
  816. FONTSIZE <value>
  817.  
  818.   this specifies the size of the font that the tcpdl status window
  819.   should use. The height of the window will be adjusted appropriately.
  820.   By default a font size of 9 will be used. This option can be
  821.   overridden by the FONTSIZE command line option.
  822.  
  823. PRIORITY <number>
  824.  
  825.   this specifies the maximum priority to be used by the tcpdl tasks.
  826.   Priorities must be in the range 0 to 5 inclusive. By default a
  827.   priority of 2 will be used. This option can be overridden by use
  828.   of the PRIORITY command line option. Using a value of 0 may be 
  829.   useful if you want tcpdl to operate in the background while you
  830.   are using a browser or IRC client.
  831.  
  832.  
  833. e.g. The following is an example of what may appear in tcpdl.config
  834.  
  835. #
  836. # Specify the Demon Internet proxy server
  837. #
  838. PROXY www-cache.demon.co.uk:8080
  839.  
  840. #
  841. # Specify the timeouts - small since we're using a proxy
  842. #
  843. CONTIMEOUT 10
  844. HTTPTIMEOUT 30
  845.  
  846. #
  847. # Specify the number of attempts for each file
  848. #
  849. RETRIES 2
  850.  
  851. #
  852. # Specify that no mail address is to be sent to the server
  853. #
  854. USER
  855.  
  856. #
  857. # Specify the number of URLs to be downloaded concurrently.
  858. # This can be overridden by the TASKS command line option.
  859. #
  860. TASKS 12
  861.  
  862. #
  863. # Specify the maximum priority to be used by the tcpdl tasks
  864. #
  865. PRIORITY 2
  866.  
  867. #
  868. # Specify the FONT and SFONTSIZE to be used
  869. #
  870. FONT Xen
  871. FONTSIZE 9
  872.  
  873. #
  874. # Specify the file suffixes not to be downloaded
  875. #
  876.  
  877. # ignore lha archives
  878. IGNORE .lha
  879.  
  880. # ignore zip archives
  881. IGNORE .zip
  882.  
  883. # ignore .wav sound files
  884. IGNORE .wav
  885.  
  886. # ignore MS-DOS executables
  887. IGNORE .exe
  888.  
  889.  
  890. THE FILE "TCPDLDIR:tcpdlpp.config":
  891. -----------------------------------
  892.  
  893. The tcpdlpp.config file is optional. If present, the character translations
  894. defined in it are applied to each URL processed. Note that the actual file
  895. names are NOT changed, but only the URLs within each html file.
  896.  
  897. Each line of this file consists of a character literal to be converted
  898. and a character literal or string that should replace it. Character
  899. literals should be enclosed by single quotes ('), and strings should
  900. be enclosed by double quotes (").
  901.  
  902. White spaces (spaces and tabs) are ignored unless inside a string.
  903.  
  904. Any line where the first non-whitespace character is a hash (#) is 
  905. treated as a comment and ignored.
  906.  
  907. Certain escape characters are allowed in character literals and strings:
  908.  
  909.   \a    = bell
  910.   \b    = backspace
  911.   \f    = formfeed
  912.   \n    = newline
  913.   \r    = carriage return
  914.   \t    = horizontal tab
  915.   \v    = vertical tab
  916.   \\    = backslash
  917.   \'    = single quote
  918.   \"    = double quote
  919.   \nnn  = character with octal value nnn
  920.   \xnnn = character with hexadecimal value nnn
  921.  
  922. e.g. the following line will convert MS-DOS style backslashes into the
  923. AmigaDOS & Unix style forward slashes:
  924.  
  925.   '\\'  '/'
  926.  
  927. the following line will convert tilde into the safe "%xx" equivalent:
  928.  
  929.   '~'  "%7E" 
  930.  
  931. Each character is translated using a single rule - even if the end result 
  932. includes a character which would have been translated by some other rule.
  933. This allows two characters to be swapped over.
  934.  
  935.  
  936. TCPDLPP LISTING
  937. ---------------
  938.  
  939. The tcpdlpp program post processes the files downloaded by tcpdl. It
  940. expects the same tcpdldir: assign as tcpdl does.
  941.  
  942. A listing is sent to stdout, which consists of 3 sections:
  943.  
  944. - a list of each file processed or skipped. Since only html files will 
  945.   contain URLs to be updated, all other files are skipped. This acts
  946.   as a progress indicator.
  947.  
  948. - a list of all local files. The number of references to each is given.
  949.   If a file has no references to it, either it is a top level html file,
  950.   or it is simply not referenced. If you are building a browsable copy
  951.   of your favourite sites, you may want to delete any unreferenced files 
  952.   to save disk space.
  953.  
  954. - a list of all non-local URLs. As for the local files, the number of
  955.   references made to each by the local files is given. If a particular
  956.   URL has a lot of references, you may want to download that URL too.
  957.  
  958. Each time you add or remove files from the tcpdldir:http directory, you
  959. should re-run tcpdlpp to adjust any links that require amendment.
  960.  
  961. Files which are present, but which have had the URLs which reference
  962. them modified in some way by the translations in the tcpdlpp.config file
  963. will be listed as non-local unless the file name has been modified also.
  964. If such files are listed, then the file names should be changed, and
  965. tcpdlpp re-run to identify those files as local.
  966.  
  967.  
  968. WARNING
  969. -------
  970.  
  971. Note that unless explicitly stated to the contrary, the copyright of all 
  972. files on the WWW is held by the owners of the appropriate site.
  973.  
  974. If you intend to redistribute *any* files downloaded from the WWW please
  975. ensure that you have the permission of the copyright holder to do so.
  976.  
  977.